Integration - Command Line Interface

The WonderLeak command line interface (CLI) is exposed via the WonderLeakCLI.exe program and accepts the following arguments:

Usage: WonderLeakCLI.exe [operation] [options]
Operations:
 -h, --help                                                 Display help information and exit.
 -V, --version                                              Display version information and exit.
 -P, --profile                                              Run the profiler against a target and save the session.
 -Q, --query                                                Load a session file and query it.
General options:
 -v, --verbose                                              Log output to stdout.
     --settings <filepath>                                  Load a settings.json file from <filepath> (Optional).
Profiling options:
 -X, --target-exitcode                                      Return the target processes exitcode as this processes exitcode once profiling is complete (Optional).
 -S, --session <filepath>                                   Save the profiling session to this <filepath> (Required).
 -D, --current-dir <dirpath>                                Set the target processes current working directory to <dirpath> (Optional).
 -E, --environment <value>                                  Pass the <value> to the target processes environment block (Optional).
     --profile-enable-all                                   Enable all profiling groups by default (Default).
     --profile-disable-all                                  Disable all profiling groups by default (Optional).
     --profile-windows-heap <true|false>                    Enable or disable the Windows Heap profiling group (Optional).
     --profile-windows-thread-local-storage <true|false>    Enable or disable the Windows TLS profiling group (Optional).
     --profile-windows-fiber-local-storage <true|false>     Enable or disable the Windows FLS profiling group (Optional).
     --profile-windows-critical-section <true|false>        Enable or disable the Windows Critical Section profiling group (Optional).
     --profile-windows-handle <true|false>                  Enable or disable the Windows Handle profiling group (Optional).
     --profile-borland-heap <true|false>                    Enable or disable the Borland Heap profiling group (Optional).
     --profile-user-types <true|false>                      Enable or disable the user types profiling group (Optional).
 -C, --call-stack-max <num>                                 Set the maximum depth of recorded call stacks, between 0 and 96 (Default 96).
 -M, --memory-data-size <num>                               Set the maximum amount of bytes to capture for allocated heap memory blocks, between 0 and 256 (Default 256)
     --ignore-dllload-allocations <true|false>              Enable or disable ignoring allocations performed during a DLL load (Default false).
 -T, --snapshot-on-termination <true|false>                 Enable or disable creating a snapshot upon target process termination (Default true).
     -- <targetfile> [<arg> ...]                            The <targetfile> to profile. Anything after <targetfile> will be passed as arguments to the target process (Required).
Query options:
 -S, --session <filepath>                                   Load the profiling session from this <filepath> (Required).
     --list-snapshots                                       List the snapshots in a session (The number of snapshots listed is returned as the exitcode).
     --list-allocations <index|name> [<index|name>]         List the allocations in a snapshot specified by <index|name>, or compare two snapshots <index|name> <index|name> and list the results (The first snapshot has an index of 1. The number of allocations listed is returned as the exitcode).
     --filter-none                                          Do not apply any filters when listing allocations.
     --filter-default                                       Apply the default filters when listing allocations (Default).
     --text-include <text>                                  Include any allocation entry containing <text>, otherwise it is excluded. --text-include can be specified multiple times.
     --text-exclude <text>                                  Exclude any allocation entry containing <text>. --text-exclude can be specified multiple times.

When profiling, the CLI will always return 0 on success or -1 on failure, unless the --target-exitcode option is used whereby the target processes exitcode is return by the CLI.

When querying, the CLI will return the number of items listed or -1 on failure.

Profiling a target

A simple example to profile a target application and save the session to a file is as follows:

WonderLeakCLI.exe -P -S out1.wdls -E PROFILING=1;FOO=BAR; -- c:\path\to\target.exe /targetparam1 

Afterwards the session file out1.wdls may be either opened in the WonderLeak GUI or queried via the CLI.

A session file generated by the WonderLeak CLI can be opened in the WonderLeak GUI running on a different system, as all required information is now stored in the session file.

Querying a session

You can query a session which has been previously saved to file, for example:

WonderLeakCLI.exe -Q -S out1.wdls -v --list-allocations 1 --filter-none

This will print every allocation in the sessions first snapshot to stdout (as the verbose -v switch was used). The return value of the CLI will be the number of allocations listed.

If the session has multiple snapshots, you can compare two snapshots and list allocations from the result of the comparison, for example:

WonderLeakCLI.exe -Q -S out1.wdls -v --list-allocations 1 2 --filter-default --text-include added

This will compare the snapshot at index 1 against the snapshot at index 2 and list the result of the comparison, but only those results that include the text "added" will be listed.

Integrate WonderLeak into your continuous integration pipeline via session profiling and querying.

If you are using the API you can create snapshots with a custom name. You can provide the custom name instead of an index when specifying a snapshot, for example --list-allocations "Snap 1" "Snap 2" will compare the snapshot named "Snap 1" against the snapshot named "Snap 2".